Main Page Modules Compound List File List Compound Members File Members Related Pages

# db-lib internals
[db-lib API]

Functions called within `db-lib` for self-help. More...

## Functions
RETCODE | dbsetlname (LOGINREC *login, const char *value, int which)
| Set the value of a string in a `LOGINREC` structure. Called by various macros to populate login.
RETCODE | dbsetllong (LOGINREC *login, long value, int which)
| Set an integer value in a `LOGINREC` structure. Called by various macros to populate login.
RETCODE | dbsetlshort (LOGINREC *login, int value, int which)
| Set an integer value in a `LOGINREC` structure. Called by various macros to populate login.
RETCODE | dbsetlbool (LOGINREC *login, int value, int which)
| Set a boolean value in a `LOGINREC` structure. Called by various macros to populate login.
DBPROCESS * | tdsdbopen (LOGINREC *login, char *server)
| Form a connection with the server.
RETCODE | dbresults_r (DBPROCESS *dbproc, int recursive)
| Recursively do what dbresults does, purportedly.
DBINT | dbcount (DBPROCESS *dbproc)
| Get count of rows processed.
RETCODE | dbrows (DBPROCESS *dbproc)
| Indicate whether a query returned rows.
RETCODE | dbcmdrow (DBPROCESS *dbproc)
| See if the current command can return rows.
DBBOOL | dbdead (DBPROCESS *dbproc)
| Check if dbproc is an ex-parrot.
DBINT | dbcurrow (DBPROCESS *dbproc)
| Get number of the row currently being read.
STATUS | dbrowtype (DBPROCESS *dbproc)
| Get returned row's type.
int | dbcurcmd (DBPROCESS *dbproc)
| Get number of the row just returned.
int | dbtds (DBPROCESS *dbproc)
| Get the TDS version in use for dbproc.
DBINT | dblastrow (DBPROCESS *dbproc)
| Get number of the last row in the row buffer.
DBINT | dbfirstrow (DBPROCESS *dbproc)
| Get number of the first row in the row buffer.
int | dbiordesc (DBPROCESS *dbproc)
| Get file descriptor of the socket used by a `DBPROCESS` to read data coming from the server. (!).
int | dbiowdesc (DBPROCESS *dbproc)
| Get file descriptor of the socket used by a `DBPROCESS` to write data coming to the server. (!).
DBBOOL | dbisavail (DBPROCESS *dbproc)
| See if a `DBPROCESS` is marked "available".
void | dbsetavail (DBPROCESS *dbproc)
| Mark a `DBPROCESS` as "available".
int | _dblib_client_msg (DBPROCESS *dbproc, int dberr, int severity, const char *dberrstr)
| Pass a server-generated error message to the client's installed handler.

## Detailed Description

Functions called within `db-lib` for self-help.

## Function Documentation

int _dblib_client_msg | ( | DBPROCESS * | dbproc,
|  | int | dberr,
|  | int | severity,
|  | const char * | dberrstr
| ) |

  | Pass a server-generated error message to the client's installed handler. For internal use only. Parameters:
  dbproc | contains all information needed by db-lib to manage communications with the server.
  dberr | error number
  severity | severity level
  dberrstr | null-terminated ASCII string, the error message.
Returns: Propogates return code of tds_client_msg(). See also: tds_client_msg().

RETCODE dbcmdrow | ( | DBPROCESS * | dbproc | ) |

  | See if the current command can return rows. For internal use only. Parameters:
  dbproc | contains all information needed by db-lib to manage communications with the server.
  Return values:
  SUCCEED | Yes, it can.
  FAIL | No, it can't.
Remarks: Use DBCMDROW() macro instead. See also: DBCMDROW(), dbnextrow(), dbresults(), DBROWS(), DBROWTYPE().

DBINT dbcount | ( | DBPROCESS * | dbproc | ) |

  | Get count of rows processed. For internal use only. Parameters:
  dbproc | contains all information needed by db-lib to manage communications with the server.
Returns: for insert/update/delete, count of rows affected. for select, count of rows returned, after all rows have been fetched. See also: DBCOUNT(), dbnextrow(), dbresults().

int dbcurcmd | ( | DBPROCESS * | dbproc | ) |

  | Get number of the row just returned. For internal use only. Parameters:
  dbproc | contains all information needed by db-lib to manage communications with the server.
See also: DBCURROW(). Todo: Unimplemented.

DBINT dbcurrow | ( | DBPROCESS * | dbproc | ) |

  | Get number of the row currently being read. For internal use only. Parameters:
  dbproc | contains all information needed by db-lib to manage communications with the server.
  Returns: ostensibly the row number, or 0 if no rows have been read yet. Return values:
  0 | Always.
See also: DBCURROW(), dbclrbuf(), DBFIRSTROW(), dbgetrow(), DBLASTROW(), dbnextrow(), dbsetopt(),. Todo: Unimplemented.

DBBOOL dbdead | ( | DBPROCESS * | dbproc | ) |

  | Check if dbproc is an ex-parrot. For internal use only. Parameters:
  dbproc | contains all information needed by db-lib to manage communications with the server.
  Return values:
  TRUE | process has been marked dead.
  FALSE | process is OK.
Remarks: dbdead() does not communicate with the server. Unless a previously db-lib marked dbproc dead, dbdead() returns `FALSE`. See also: dberrhandle().

DBINT dbfirstrow | ( | DBPROCESS * | dbproc | ) |

  | Get number of the first row in the row buffer. For internal use only. Parameters:
  dbproc | contains all information needed by db-lib to manage communications with the server.
See also: DBFIRSTROW(), dbclrbuf(), DBCURROW(), dbgetrow(), DBLASTROW(), dbnextrow(), dbsetopt().

int dbiordesc | ( | DBPROCESS * | dbproc | ) |

  | Get file descriptor of the socket used by a `DBPROCESS` to read data coming from the server. (!). For internal use only. Parameters:
  dbproc | contains all information needed by db-lib to manage communications with the server.
See also: dbcmd(), DBIORDESC(), DBIOWDESC(), dbnextrow(), dbpoll(), DBRBUF(), dbresults(), dbsqlok(), dbsqlsend().

int dbiowdesc | ( | DBPROCESS * | dbproc | ) |

  | Get file descriptor of the socket used by a `DBPROCESS` to write data coming to the server. (!). For internal use only. Parameters:
  dbproc | contains all information needed by db-lib to manage communications with the server.
See also: dbcmd(), DBIORDESC(), DBIOWDESC(), dbnextrow(), dbpoll(), DBRBUF(), dbresults(), dbsqlok(), dbsqlsend().

DBBOOL dbisavail | ( | DBPROCESS * | dbproc | ) |

  | See if a `DBPROCESS` is marked "available". For internal use only. Parameters:
  dbproc | contains all information needed by db-lib to manage communications with the server.
  Remarks: Basically bogus. `FreeTDS` behaves the way Sybase's implementation does, but so what? Many `db-lib` functions set the `DBPROCESS` to "not available", but only dbsetavail() resets it to "available". Return values:
  TRUE | dbproc is "available".
  FALSE | dbproc is not "available".
See also: DBISAVAIL(). DBSETAVAIL().

DBINT dblastrow | ( | DBPROCESS * | dbproc | ) |

  | Get number of the last row in the row buffer. For internal use only. Parameters:
  dbproc | contains all information needed by db-lib to manage communications with the server.
See also: DBLASTROW(), dbclrbuf(), DBCURROW(), DBFIRSTROW(), dbgetrow(), dbnextrow(), dbsetopt().

RETCODE dbresults_r | ( | DBPROCESS * | dbproc,
|  | int | recursive
| ) |

  | Recursively do what dbresults does, purportedly. For internal use only. Parameters:
  dbproc | contains all information needed by db-lib to manage communications with the server.
  recursive | Not used.
Remarks: Is this really an internal process and, if not, where is it documented? See also:

RETCODE dbrows | ( | DBPROCESS * | dbproc | ) |

  | Indicate whether a query returned rows. For internal use only. Parameters:
  dbproc | contains all information needed by db-lib to manage communications with the server.
See also: DBROWS(), DBCMDROW(), dbnextrow(), dbresults(), DBROWTYPE().

STATUS dbrowtype | ( | DBPROCESS * | dbproc | ) |

  | Get returned row's type. For internal use only. Parameters:
  dbproc | contains all information needed by db-lib to manage communications with the server.
See also: DBROWTYPE(). Todo: Unimplemented.

void dbsetavail | ( | DBPROCESS * | dbproc | ) |

  | Mark a `DBPROCESS` as "available". For internal use only. Parameters:
  dbproc | contains all information needed by db-lib to manage communications with the server.
Remarks: Basically bogus. `FreeTDS` behaves the way Sybase's implementation does, but so what? Many `db-lib` functions set the `DBPROCESS` to "not available", but only dbsetavail() resets it to "available". See also: DBISAVAIL(). DBSETAVAIL().

RETCODE dbsetlbool | ( | LOGINREC * | login,
|  | int | value,
|  | int | which
| ) |

  | Set a boolean value in a `LOGINREC` structure. Called by various macros to populate login. For internal use only. Parameters:
  login | the `LOGINREC*` to modify.
  value | the value to set it to.
  which | the field to set.
  Return values:
  SUCCEED | the value was set.
  FAIL | invalid value passed for which.

RETCODE dbsetllong | ( | LOGINREC * | login,
|  | long | value,
|  | int | which
| ) |

  | Set an integer value in a `LOGINREC` structure. Called by various macros to populate login. For internal use only. Parameters:
  login | the `LOGINREC*` to modify.
  value | the value to set it to.
  which | the field to set.
  Return values:
  SUCCEED | the value was set.
  FAIL | anything other than `DBSETPACKET` was passed for which.

RETCODE dbsetlname | ( | LOGINREC * | login,
|  | const char * | value,
|  | int | which
| ) |

  | Set the value of a string in a `LOGINREC` structure. Called by various macros to populate login. For internal use only. Parameters:
  login | the `LOGINREC*` to modify.
  value | the value to set it to.
  which | the field to set.
  Return values:
  SUCCEED | the value was set.
  FAIL | `DBSETHID` or other invalid which was tried.

RETCODE dbsetlshort | ( | LOGINREC * | login,
|  | int | value,
|  | int | which
| ) |

  | Set an integer value in a `LOGINREC` structure. Called by various macros to populate login. For internal use only. Parameters:
  login | the `LOGINREC*` to modify.
  value | the value to set it to.
  which | the field to set.
  Return values:
  SUCCEED | the value was set.
  FAIL | anything other than `DBSETHIER` was passed for which.

int dbtds | ( | DBPROCESS * | dbproc | ) |

  | Get the TDS version in use for dbproc. For internal use only. Parameters:
  dbproc | contains all information needed by db-lib to manage communications with the server.
Returns: a `DBTDS*` token. Remarks: The integer values of the constants are counterintuitive. See also: DBTDS().

DBPROCESS* tdsdbopen | ( | LOGINREC * | login,
|  | char * | server
| ) |

  | Form a connection with the server. For internal use only. Called by the `dbopen()` macro, normally. If FreeTDS was configured with `--enable-msdblib`, this function is called by (exported) `dbopen()` function. `tdsdbopen` is so-named to avoid namespace conflicts with other database libraries that use the same function name. Parameters:
  login | `LOGINREC*` carrying the account information.
  server | name of the dataserver to connect to.
  Returns: valid pointer on successful login. Return values:
  NULL | insufficient memory, unable to connect for any reason.
Todo: use `asprintf()` to avoid buffer overflow. separate error messages for no-such-server and no-such-user.